home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / msdos / animutil / fastgfx / fg303b / manuals.arj / USER01.DOC < prev    next >
Encoding:
Text File  |  1993-10-02  |  65.7 KB  |  1,416 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18. Fastgraph (tm)
  19.  
  20.  
  21.  
  22.  
  23.  
  24. User's Guide
  25.  
  26. Copyright (c) 1991-1993 by Ted Gruber Software.
  27.  
  28. All rights reserved.  No part of this publication may be reproduced, stored
  29. in a retrieval system, or transmitted by any means, electronic, mechanical,
  30. photocopying, recording, or otherwise, without express written permission
  31. from Ted Gruber Software.  The software described in this publication is
  32. furnished under a license agreement and may be used or copied only in
  33. accordance with the terms of that agreement.
  34.  
  35. This publication and its associated software are sold without warranties,
  36. either expressed or implied, regarding their merchantability or fitness for
  37. any particular application or purpose.  The information in this publication
  38. is subject to change without notice and does not represent a commitment on
  39. the part of Ted Gruber Software.  In no event shall Ted Gruber Software be
  40. liable for any loss of profit or any other commercial damage, including but
  41. not limited to special, incidental, consequential, or other damages resulting
  42. from the use of or the inability to use this product, even if Ted Gruber
  43. Software has been notified of the possibility of such damages.
  44.  
  45.  
  46. First Printing, April 1993
  47.  
  48. Fastgraph version 3.00
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60. All brand and product names mentioned in this publication are trademarks or
  61. registered trademarks of their respective holders.
  62.  
  63.  
  64.  
  65.  
  66.  
  67.                       T a b l e   o f   C o n t e n t s
  68.  
  69.  
  70. Chapter 1  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .    1
  71.      What is Fastgraph? . . . . . . . . . . . . . . . . . . . . . . . . .    2
  72.      Fastgraph/Light  . . . . . . . . . . . . . . . . . . . . . . . . . .    2
  73.      Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . .    2
  74.      Supported Compilers  . . . . . . . . . . . . . . . . . . . . . . . .    3
  75.      Memory Models  . . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  76.      Installing Fastgraph . . . . . . . . . . . . . . . . . . . . . . . .    4
  77.      The READ.ME File . . . . . . . . . . . . . . . . . . . . . . . . . .    5
  78.      Fastgraph Naming Conventions . . . . . . . . . . . . . . . . . . . .    5
  79.      Compilation and Linking  . . . . . . . . . . . . . . . . . . . . . .    5
  80.           Borland C++ . . . . . . . . . . . . . . . . . . . . . . . . . .    8
  81.           Borland Pascal  . . . . . . . . . . . . . . . . . . . . . . . .   10
  82.           Microsoft BASIC PDS 7 . . . . . . . . . . . . . . . . . . . . .   11
  83.           Microsoft C and C++ . . . . . . . . . . . . . . . . . . . . . .   13
  84.           Microsoft FORTRAN . . . . . . . . . . . . . . . . . . . . . . .   14
  85.           Microsoft QuickBASIC  . . . . . . . . . . . . . . . . . . . . .   16
  86.           Microsoft QuickC  . . . . . . . . . . . . . . . . . . . . . . .   18
  87.           Microsoft Visual Basic for DOS  . . . . . . . . . . . . . . . .   20
  88.           Microsoft Visual C++  . . . . . . . . . . . . . . . . . . . . .   22
  89.           Power C . . . . . . . . . . . . . . . . . . . . . . . . . . . .   23
  90.           Turbo C and Turbo C++ . . . . . . . . . . . . . . . . . . . . .   25
  91.           Turbo Pascal  . . . . . . . . . . . . . . . . . . . . . . . . .   27
  92.           Zortech C++ . . . . . . . . . . . . . . . . . . . . . . . . . .   28
  93.      Fastgraph/Light Video Driver . . . . . . . . . . . . . . . . . . . .   29
  94.  
  95. Chapter 2  PC and PS/2 Video Modes  . . . . . . . . . . . . . . . . . . .   31
  96.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   32
  97.      Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   33
  98.      Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . .   35
  99.           CGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   35
  100.           Tandy 1000 and PCjr Graphics Modes  . . . . . . . . . . . . . .   36
  101.           Hercules Graphics Modes . . . . . . . . . . . . . . . . . . . .   36
  102.           EGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   37
  103.           VGA and MCGA Graphics Modes . . . . . . . . . . . . . . . . . .   38
  104.           Extended VGA (XVGA) Graphics Modes  . . . . . . . . . . . . . .   39
  105.           SuperVGA (SVGA) Graphics Modes  . . . . . . . . . . . . . . . .   40
  106.  
  107. Chapter 3  Initializing the Video Environment . . . . . . . . . . . . . .   43
  108.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   44
  109.      Establishing a Text Mode . . . . . . . . . . . . . . . . . . . . . .   44
  110.      43-line and 50-line Text Modes . . . . . . . . . . . . . . . . . . .   47
  111.      Establishing a Graphics Mode . . . . . . . . . . . . . . . . . . . .   48
  112.      SuperVGA Graphics Modes  . . . . . . . . . . . . . . . . . . . . . .   51
  113.      Summary of Video Initialization Routines . . . . . . . . . . . . . .   56
  114.  
  115. Chapter 4  Coordinate Systems . . . . . . . . . . . . . . . . . . . . . .   59
  116.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   60
  117.      Character Space  . . . . . . . . . . . . . . . . . . . . . . . . . .   60
  118.      Screen Space . . . . . . . . . . . . . . . . . . . . . . . . . . . .   61
  119.  
  120.                                      iii
  121.  
  122.      World Space  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   62
  123.      Conversion Routines  . . . . . . . . . . . . . . . . . . . . . . . .   64
  124.      Summary of Coordinate Routines . . . . . . . . . . . . . . . . . . .   64
  125.  
  126. Chapter 5  The Use of Color . . . . . . . . . . . . . . . . . . . . . . .   67
  127.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   68
  128.      Text Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   68
  129.           Color Text Modes  . . . . . . . . . . . . . . . . . . . . . . .   68
  130.           Monochrome Text Mode  . . . . . . . . . . . . . . . . . . . . .   69
  131.      Graphics Modes . . . . . . . . . . . . . . . . . . . . . . . . . . .   70
  132.           CGA Color Modes . . . . . . . . . . . . . . . . . . . . . . . .   70
  133.           CGA Two-Color Mode  . . . . . . . . . . . . . . . . . . . . . .   72
  134.           Tandy and PCjr Modes  . . . . . . . . . . . . . . . . . . . . .   73
  135.           Hercules Mode . . . . . . . . . . . . . . . . . . . . . . . . .   74
  136.           Hercules Low-Resolution Mode  . . . . . . . . . . . . . . . . .   75
  137.           EGA 200-Line Modes  . . . . . . . . . . . . . . . . . . . . . .   76
  138.           EGA Monochrome Mode . . . . . . . . . . . . . . . . . . . . . .   78
  139.           EGA Enhanced Mode . . . . . . . . . . . . . . . . . . . . . . .   79
  140.           VGA and MCGA Two-Color Mode . . . . . . . . . . . . . . . . . .   81
  141.           VGA/SVGA 16-Color Modes . . . . . . . . . . . . . . . . . . . .   83
  142.           256-Color Modes . . . . . . . . . . . . . . . . . . . . . . . .   83
  143.      Using Video DAC Registers in EGA Modes . . . . . . . . . . . . . . .   87
  144.      RGB Color Mapping  . . . . . . . . . . . . . . . . . . . . . . . . .   89
  145.      Defining All Palette Registers . . . . . . . . . . . . . . . . . . .   90
  146.      Virtual Colors . . . . . . . . . . . . . . . . . . . . . . . . . . .   90
  147.      A Multiple-Mode Example  . . . . . . . . . . . . . . . . . . . . . .   92
  148.      Summary of Color-Related Routines  . . . . . . . . . . . . . . . . .   94
  149.  
  150. Chapter 6  Graphics Fundamentals  . . . . . . . . . . . . . . . . . . . .   97
  151.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  152.      Clearing the Screen  . . . . . . . . . . . . . . . . . . . . . . . .   98
  153.      Clipping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  154.      Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   99
  155.      The Graphics Cursor  . . . . . . . . . . . . . . . . . . . . . . . .  101
  156.      Solid Lines  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  102
  157.      Dashed Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . .  104
  158.      Polygons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  105
  159.      Circles and Ellipses . . . . . . . . . . . . . . . . . . . . . . . .  109
  160.      Solid Rectangles . . . . . . . . . . . . . . . . . . . . . . . . . .  111
  161.      Unfilled Rectangles  . . . . . . . . . . . . . . . . . . . . . . . .  112
  162.      Dithered Rectangles  . . . . . . . . . . . . . . . . . . . . . . . .  114
  163.      Region Fill  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  121
  164.      Summary of Fundamental Graphics Routines . . . . . . . . . . . . . .  122
  165.  
  166. Chapter 7  Character Display Routines . . . . . . . . . . . . . . . . . .  127
  167.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  128
  168.      Character Space  . . . . . . . . . . . . . . . . . . . . . . . . . .  128
  169.      Hardware Characters  . . . . . . . . . . . . . . . . . . . . . . . .  129
  170.      Character Height . . . . . . . . . . . . . . . . . . . . . . . . . .  137
  171.      Conversion Routines  . . . . . . . . . . . . . . . . . . . . . . . .  138
  172.      Software Characters  . . . . . . . . . . . . . . . . . . . . . . . .  139
  173.      Bit-Mapped Characters  . . . . . . . . . . . . . . . . . . . . . . .  145
  174.      Summary of Character Display Routines  . . . . . . . . . . . . . . .  145
  175.  
  176. Chapter 8  Video Page Management  . . . . . . . . . . . . . . . . . . . .  149
  177.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  150
  178.  
  179.                                       iv
  180.  
  181.      Physical Pages and Virtual Pages . . . . . . . . . . . . . . . . . .  150
  182.      Pages With Special Meanings  . . . . . . . . . . . . . . . . . . . .  151
  183.      Some Simple Examples . . . . . . . . . . . . . . . . . . . . . . . .  152
  184.      Text Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . .  159
  185.      Obtaining Video Page Information . . . . . . . . . . . . . . . . . .  160
  186.      Considerations for Virtual Pages . . . . . . . . . . . . . . . . . .  161
  187.      Logical Pages  . . . . . . . . . . . . . . . . . . . . . . . . . . .  162
  188.      Video Page Resizing  . . . . . . . . . . . . . . . . . . . . . . . .  164
  189.      Preserving Video Page Contents Across Mode Switches  . . . . . . . .  166
  190.      Controlling Page Allocation  . . . . . . . . . . . . . . . . . . . .  167
  191.      Summary of Video Page Management Routines  . . . . . . . . . . . . .  169
  192.  
  193. Chapter 9  Image Files  . . . . . . . . . . . . . . . . . . . . . . . . .  171
  194.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
  195.      PCX Files  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  172
  196.      GIF Files  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  175
  197.      Pixel Run Files  . . . . . . . . . . . . . . . . . . . . . . . . . .  176
  198.      Display Patterns . . . . . . . . . . . . . . . . . . . . . . . . . .  181
  199.      Controlling the Image Buffer Size  . . . . . . . . . . . . . . . . .  186
  200.      Summary of Image File Routines . . . . . . . . . . . . . . . . . . .  187
  201.  
  202. Chapter 10  Bit-Mapped Images . . . . . . . . . . . . . . . . . . . . . .  189
  203.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  190
  204.      Mode-Independent Bit-Mapped Images . . . . . . . . . . . . . . . . .  190
  205.      Mode-Specific Bit-Mapped Images  . . . . . . . . . . . . . . . . . .  194
  206.           Regular Images  . . . . . . . . . . . . . . . . . . . . . . . .  195
  207.           Clipped Images  . . . . . . . . . . . . . . . . . . . . . . . .  203
  208.           Reversed Images . . . . . . . . . . . . . . . . . . . . . . . .  203
  209.           Reversed Clipped Images . . . . . . . . . . . . . . . . . . . .  203
  210.           Images Without Transparent Pixels . . . . . . . . . . . . . . .  203
  211.           Some Examples . . . . . . . . . . . . . . . . . . . . . . . . .  203
  212.      Retrieving Images  . . . . . . . . . . . . . . . . . . . . . . . . .  207
  213.      Pixel Run Maps . . . . . . . . . . . . . . . . . . . . . . . . . . .  212
  214.      Masking Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . .  215
  215.      Summary of Bit-Mapped Image Display Routines . . . . . . . . . . . .  219
  216.  
  217. Chapter 11  Block Transfer Routines . . . . . . . . . . . . . . . . . . .  221
  218.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  222
  219.      Full Page Transfer . . . . . . . . . . . . . . . . . . . . . . . . .  222
  220.      Byte Boundaries  . . . . . . . . . . . . . . . . . . . . . . . . . .  223
  221.      Dual SVGA Banks  . . . . . . . . . . . . . . . . . . . . . . . . . .  224
  222.      The "Hidden" Video Page  . . . . . . . . . . . . . . . . . . . . . .  225
  223.      Saving and Restoring Blocks  . . . . . . . . . . . . . . . . . . . .  225
  224.      A More General Block Transfer Routine  . . . . . . . . . . . . . . .  228
  225.      Blocks with Transparent Colors . . . . . . . . . . . . . . . . . . .  231
  226.      Transferring Blocks to and from Conventional Memory  . . . . . . . .  233
  227.      Summary of Block Transfer Routines . . . . . . . . . . . . . . . . .  234
  228.  
  229. Chapter 12  Animation Techniques  . . . . . . . . . . . . . . . . . . . .  237
  230.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  238
  231.      Simple Animation . . . . . . . . . . . . . . . . . . . . . . . . . .  238
  232.      XOR Animation  . . . . . . . . . . . . . . . . . . . . . . . . . . .  240
  233.      Static Frame Animation . . . . . . . . . . . . . . . . . . . . . . .  242
  234.      Dynamic Frame Animation  . . . . . . . . . . . . . . . . . . . . . .  244
  235.      Page Flipping  . . . . . . . . . . . . . . . . . . . . . . . . . . .  246
  236.      An Animation Example:  The Fastgraph Fish Tank . . . . . . . . . . .  248
  237.  
  238.                                       v
  239.  
  240.      Summary of Animation Techniques  . . . . . . . . . . . . . . . . . .  248
  241.  
  242. Chapter 13  Special Effects . . . . . . . . . . . . . . . . . . . . . . .  249
  243.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  250
  244.      Screen Dissolving  . . . . . . . . . . . . . . . . . . . . . . . . .  250
  245.      Scrolling  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  252
  246.      Changing the Screen Origin . . . . . . . . . . . . . . . . . . . . .  255
  247.      Summary of Special Effects Routines  . . . . . . . . . . . . . . . .  258
  248.  
  249. Chapter 14  Input Device Support  . . . . . . . . . . . . . . . . . . . .  259
  250.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  260
  251.      Keyboard Support . . . . . . . . . . . . . . . . . . . . . . . . . .  260
  252.           Reading Keystrokes  . . . . . . . . . . . . . . . . . . . . . .  262
  253.           Testing and Setting Key States  . . . . . . . . . . . . . . . .  263
  254.           Low-Level Keyboard Handler  . . . . . . . . . . . . . . . . . .  264
  255.      Mouse Support  . . . . . . . . . . . . . . . . . . . . . . . . . . .  266
  256.           Initializing the Mouse  . . . . . . . . . . . . . . . . . . . .  267
  257.           XVGA and SVGA Mouse Considerations  . . . . . . . . . . . . . .  268
  258.           Controlling the Mouse Cursor  . . . . . . . . . . . . . . . . .  269
  259.           Reporting the Mouse Status  . . . . . . . . . . . . . . . . . .  271
  260.           Defining the Mouse Cursor . . . . . . . . . . . . . . . . . . .  273
  261.      Joystick Support . . . . . . . . . . . . . . . . . . . . . . . . . .  279
  262.           Initializing Joysticks  . . . . . . . . . . . . . . . . . . . .  279
  263.           Reporting Joystick Status . . . . . . . . . . . . . . . . . . .  280
  264.           Keyboard Emulation  . . . . . . . . . . . . . . . . . . . . . .  281
  265.           Special Joystick Considerations . . . . . . . . . . . . . . . .  283
  266.      Summary of Input Routines  . . . . . . . . . . . . . . . . . . . . .  283
  267.  
  268. Chapter 15  Sound Effects . . . . . . . . . . . . . . . . . . . . . . . .  285
  269.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  286
  270.      Sound Sources  . . . . . . . . . . . . . . . . . . . . . . . . . . .  286
  271.      Synchronous Sound  . . . . . . . . . . . . . . . . . . . . . . . . .  286
  272.      Asynchronous Sound . . . . . . . . . . . . . . . . . . . . . . . . .  290
  273.      Summary of Sound Routines  . . . . . . . . . . . . . . . . . . . . .  296
  274.  
  275. Chapter 16  Program Timing  . . . . . . . . . . . . . . . . . . . . . . .  299
  276.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  300
  277.      Real-Time Routines . . . . . . . . . . . . . . . . . . . . . . . . .  300
  278.      Routines Dependent on the System Speed . . . . . . . . . . . . . . .  301
  279.      Summary of Timing Routines . . . . . . . . . . . . . . . . . . . . .  303
  280.  
  281. Chapter 17  Miscellaneous Routines  . . . . . . . . . . . . . . . . . . .  303
  282.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  304
  283.      Determining Available Memory . . . . . . . . . . . . . . . . . . . .  304
  284.      Choosing the Video Memory Update Function  . . . . . . . . . . . . .  305
  285.      Controlling Vertical Retrace Synchronization . . . . . . . . . . . .  306
  286.      Summary of Miscellaneous Routines  . . . . . . . . . . . . . . . . .  307
  287.  
  288. Appendix A  Fastgraph Utilities . . . . . . . . . . . . . . . . . . . . .  309
  289.      Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  310
  290.      SNAPSHOT Utility . . . . . . . . . . . . . . . . . . . . . . . . . .  310
  291.      CLIP Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . .  311
  292.      CONVERT Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  312
  293.      EDITSPR Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  313
  294.      GrabRGB Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  313
  295.      HERCFIX Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  314
  296.  
  297.                                       vi
  298.  
  299.      PCXHEAD Utility  . . . . . . . . . . . . . . . . . . . . . . . . . .  315
  300.  
  301. Appendix B  Using Fastgraph from Assembly Language  . . . . . . . . . . .  317
  302.  
  303. Appendix C  Interrupts and Fastgraph  . . . . . . . . . . . . . . . . . .  321
  304.      Interrupts Used by Fastgraph . . . . . . . . . . . . . . . . . . . .  322
  305.      Extending the Time-of-Day Interrupt  . . . . . . . . . . . . . . . .  322
  306.  
  307. Appendix D  Contents of the Compiler-Specific Libraries . . . . . . . . .  329
  308.  
  309. Appendix E  Contents of the Pascal Unit Files . . . . . . . . . . . . . .  331
  310.  
  311. Appendix F  Integrating Fastgraph With Other Graphics Software  . . . . .  333
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.                                      vii
  357. Chapter 1
  358.  
  359.  
  360.  
  361.  
  362.  
  363. Introduction
  364.  
  365. 2   Fastgraph User's Guide
  366.  
  367.  
  368.  
  369. What is Fastgraph?
  370.  
  371.      Fastgraph is a library of more than 200 highly-optimized routines that
  372. are callable from high-level and assembly language programs running under the
  373. MS-DOS or PC-DOS operating systems.  This collection of routines provides a
  374. programmer with proven, powerful tools to take command of the PC and PS/2
  375. video environment.  In addition to its video support, Fastgraph also includes
  376. routines to perform keyboard, mouse, and joystick control, as well as music
  377. and sound capabilities.  Fastgraph is an ideal development tool for
  378. entertainment and educational software, presentation graphics products,
  379. scientific and engineering applications, CAD/CAM, animation, or any
  380. application that demands robust graphics.
  381.  
  382.      As its name implies, the most notable feature of Fastgraph is its speed.
  383. Virtually all of Fastgraph is written in 8086 assembly language, and each
  384. routine has been optimized by hand to provide maximum performance.
  385.  
  386.      Fastgraph supports all the standard text and graphics video modes used
  387. by the IBM PC (PC, PC/XT, and PC/AT) and PS/2 families and compatible
  388. systems.  In addition, Fastgraph provides support for six SuperVGA (SVGA)
  389. graphics modes, four extended VGA (XVGA) graphics modes, and a 16-color
  390. graphics mode unique to Tandy 1000 series computers and the PCjr.  Even
  391. though the graphics mode of the Hercules Graphics Card is not an IBM
  392. standard, its popularity has made it a de facto standard, and for this reason
  393. Fastgraph also supports it.  In total, Fastgraph supports 23 graphics modes
  394. and 5 text modes.  A complete discussion of these video modes appears in the
  395. next chapter.
  396.  
  397.  
  398. Fastgraph/Light
  399.  
  400.      Fastgraph/Light is a subset of Fastgraph.  It includes all of
  401. Fastgraph's features except the redefinable world space coordinate system and
  402. the routines pertaining to software characters.  Programs created using
  403. Fastgraph/Light are 100% source code compatible with Fastgraph.
  404.  
  405.      The most important difference between Fastgraph/Light and Fastgraph is
  406. the method of running a program created with the two products.  With
  407. Fastgraph, any of its routines used in your program are linked directly into
  408. the resulting .EXE file.  With Fastgraph/Light, however, this is not the
  409. case.  Instead, the Fastgraph/Light routines provide an interface to an
  410. external driver, called the Fastgraph/Light Video Driver, which must be
  411. loaded separately before running programs that call any Fastgraph/Light
  412. routines.  See the last section of this chapter for more information.
  413.  
  414.      In this document, and in the accompanying Fastgraph Reference Manual,
  415. references to Fastgraph also apply to Fastgraph/Light unless stated
  416. otherwise.
  417.  
  418.  
  419. Prerequisite Knowledge
  420.  
  421.      Fastgraph is a programming tool, which means programmers are its
  422. intended audience.  For this reason, the Fastgraph User's Guide and the
  423. accompanying Fastgraph Reference Manual assume you have a knowledge of
  424.                                                   Chapter 1:  Introduction   3
  425.  
  426.  
  427. programming.  Additionally, a knowledge of converting numbers between binary,
  428. decimal, and hexadecimal is assumed.
  429.  
  430.      Virtually all the examples in this manual are written in the C
  431. programming language, so a knowledge of C would be especially helpful.  The
  432. examples intentionally avoid using any of C's features and idioms that might
  433. not be readily apparent to a programmer unfamiliar with C.  Finally, we'd
  434. like to point out that the examples are intended to be read not by
  435. themselves, but as part of the surrounding text.
  436.  
  437.  
  438. Supported Compilers
  439.  
  440.      You can use Fastgraph with any compilers or assemblers that use the same
  441. calling and naming conventions as the small, medium, or large memory models
  442. of the supported compilers.  Mixed language programming is allowed where
  443. supported by the language translators and linker being used.  Fastgraph
  444. supports the following compilers:
  445.  
  446.        Borland C++ (version 2.0 or later)
  447.        Borland Pascal (version 7.0 or later)
  448.        Microsoft C (version 5.0 or later)
  449.        Microsoft C++ (version 7.0 or later)
  450.        Microsoft BASIC PDS (version 7.1 or later)
  451.        Microsoft FORTRAN (version 4.0 or later)
  452.        Microsoft QuickBASIC (version 4.0 or later)
  453.        Microsoft QuickC (version 2.0 or later)
  454.        Microsoft Visual Basic for DOS (version 1.0 or later)
  455.        Microsoft Visual C++ (version 1.0 or later)
  456.        Power C (version 2.0 or later)
  457.        Turbo C (version 2.0 or later)
  458.        Turbo C++ (version 1.0 or later)
  459.        Turbo Pascal (version 6.0 or later)
  460.        Zortech C++ (version 3.0 or later)
  461.  
  462. The listed version numbers are the compiler versions under which Fastgraph
  463. was developed and tested.  Fastgraph may or may not work with earlier
  464. versions of these compilers.  As we constantly add support for new compilers,
  465. please check the READ.ME file in the \FG directory for additions to the above
  466. list.  The use of Fastgraph from assembly language programs is addressed in
  467. Appendix B.
  468.  
  469.  
  470. Memory Models
  471.  
  472.      All of Fastgraph's supported compilers except QuickBASIC, Visual Basic
  473. for DOS, Borland Pascal, and Turbo Pascal offer several memory models.  A
  474. memory model defines how memory is set up for a program's code and data
  475. segments.  Fastgraph includes libraries for the small, medium, and large
  476. memory models.
  477.  
  478.      The small memory model allows for one code segment and one data segment.
  479. Programs that use the small model can thus have a maximum of 64K bytes of
  480. code and 64K bytes of data.  Because the small model implements call
  481. instructions and data references through near pointers, it produces the most
  482. efficient code of the three supported memory models.
  483. 4   Fastgraph User's Guide
  484.  
  485.  
  486.      The medium memory model allows for multiple code segments and one data
  487. segment.  Programs that use the medium model thus have no compiler-imposed
  488. limit to the code size (although no one segment can exceed 64K bytes) and a
  489. maximum of 64K bytes of data.  Like the small model, the medium model
  490. implements data references through near pointers, but it implements call
  491. instructions through far pointers.  The use of far pointers adds two bytes of
  492. code and 13 clock cycles for each subprogram call.  The medium model is a
  493. popular choice among programmers.
  494.  
  495.      The large memory model supports multiple code and data segments.
  496. Programs that use the large model do not have any compiler-imposed limits for
  497. code and data sizes.  However, no single code or data segment can exceed 64K
  498. bytes.  Because the large model implements call instructions and data
  499. references through far pointers, it produces the least efficient code of the
  500. three supported memory models.
  501.  
  502.      For more information about memory models, please refer to the user's
  503. guide or reference manual supplied with your compiler.
  504.  
  505.  
  506. Installing Fastgraph
  507.  
  508.      This section explains how to use the INSTALL program to load Fastgraph
  509. (or Fastgraph/Light) and its related files on a hard disk.  The installation
  510. program lets you select the compilers and memory models you wish to use with
  511. Fastgraph.  It also gives you the opportunity to load many example Fastgraph
  512. programs specific to the compilers you choose.
  513.  
  514.      Before you start the installation, we recommend using the DOS commands
  515. COPY or DISKCOPY to make working copies of the Fastgraph distribution disks
  516. (refer to your DOS reference manual if you are unfamiliar with these
  517. commands).  Once you have created the working copies, store the original
  518. disks in a safe place.  Install Fastgraph from the working copies you just
  519. created.
  520.  
  521.      For simplicity, we'll assume you are installing Fastgraph from the
  522. diskette drive A: to the hard drive C:, but you can of course use any
  523. available drives.  The Fastgraph distribution disk labeled Installation and
  524. Utilities contains Fastgraph's INSTALL program.  Place this disk in the A:
  525. drive, make A: your current drive, and enter the command INSTALL, as shown
  526. below.
  527.  
  528.                                   C> A:
  529.                                   A> INSTALL
  530.  
  531. From this point, just follow the directions on each screen.  At any time, you
  532. can press the Esc key to abort the installation.
  533.  
  534.      The INSTALL program will ask you for the compilers and memory models
  535. you'll use with Fastgraph, as well as the directory names for the Fastgraph
  536. utilities, libraries, and include files.  For the utilities, the default
  537. directory is C:\FG.  For the include files and libraries, we recommend using
  538. directories where the compiler you've chosen normally searches for such
  539. files.  INSTALL will automatically try to determine these directories and
  540. propose them as defaults.
  541.                                                   Chapter 1:  Introduction   5
  542.  
  543.  
  544.      You can install support for additional compilers or memory models at any
  545. time.  If you choose to do this, you should use the command INSTALL /L to
  546. avoid copying the files common to all compilers and memory models.
  547.  
  548.  
  549. The READ.ME File
  550.  
  551.      The READ.ME file contains additions and changes that may have been made
  552. to Fastgraph since the publication of the manuals.  We encourage you to
  553. examine the READ.ME file immediately after installing Fastgraph.  READ.ME is
  554. an ASCII text file, suitable for any printer or text editor.  The INSTALL
  555. program places the READ.ME file in the Fastgraph utilities directory (C:\FG
  556. by default).
  557.  
  558.  
  559. Fastgraph Naming Conventions
  560.  
  561.      The names of all Fastgraph routines begin with the three characters
  562. "fg_".  This prefix helps identify Fastgraph routines within a program, and
  563. it also reduces the chance of name conflicts that might otherwise occur
  564. between Fastgraph and other third party libraries.
  565.  
  566.      Because QuickBASIC and Visual Basic for DOS do not permit underscores in
  567. identifiers, the BASIC versions of Fastgraph routines begin with the two
  568. characters "FG".  For example, the fg_version routine is named FGversion in
  569. the QuickBASIC and Visual Basic for DOS libraries.  All subsequent references
  570. to Fastgraph routines in this manual and the accompanying Fastgraph Reference
  571. Manual will use the fg_ naming convention instead of the BASIC names.
  572.  
  573.  
  574. Compilation and Linking
  575.  
  576.      To build an executable (.EXE) file for a program that uses Fastgraph
  577. routines, first compile or assemble the program using the small, medium, or
  578. large memory model.  This step produces an object file, which is then linked
  579. with Fastgraph and any other object libraries to produce an executable file.
  580.  
  581.      Example 1-1 uses the Fastgraph routine fg_version to display the version
  582. number for your copy of Fastgraph.  Versions of this program are presented
  583. for each high-level language Fastgraph supports:  C/C++, BASIC, FORTRAN, and
  584. Pascal.  If you loaded the example programs when you installed Fastgraph, the
  585. files \FG\EXAMPLES\01-01.C, 01-01.BAS, 01-01.FOR, and 01-01.PAS contain the
  586. source code for these examples.  You can use them to test the compilation and
  587. linking process for the memory models and compilers you'll be using with
  588. Fastgraph.
  589.  
  590.                          Example 1-1 (C/C++ version).
  591.  
  592.       #include <fastgraf.h>
  593.       #include <stdio.h>
  594.       void main(void);
  595.  
  596.       void main()
  597.       {
  598.          int major;
  599.          int minor;
  600. 6   Fastgraph User's Guide
  601.  
  602.  
  603.          fg_version(&major,&minor);
  604.          printf("This is version %d.%2.2d of Fastgraph.\n",major,minor);
  605.       }
  606.  
  607.  
  608.      The header file FASTGRAF.H contains the C function prototypes for each
  609. Fastgraph routine.  It should reside in a directory where the compiler
  610. normally searches for other header files.  For Microsoft C/C++, QuickC, and
  611. Zortech C++, FASTGRAF.H can reside in any of the directories specified by the
  612. INCLUDE environment variable.  For Power C, it can reside in any of the
  613. directories specified by the /i switch in the PCOPTION environment variable.
  614.  
  615.                          Example 1-1 (BASIC version).
  616.  
  617.           REM $INCLUDE: 'fastgraf.bi'
  618.  
  619.           DEFINT A-Z
  620.  
  621.           FGversion Major, Minor
  622.           Version! = Major + Minor*0.01
  623.  
  624.           PRINT USING "This is version #.## of Fastgraph."; Version!
  625.  
  626.           END
  627.  
  628.  
  629.      You must include the DECLARE commands in the file FASTGRAF.BI at the
  630. beginning of each QuickBASIC or Visual Basic for DOS module.  This file
  631. should reside in the directory where the compiler normally searches for other
  632. .BI files, or in any of the directories specified by the INCLUDE environment
  633. variable.  The DECLARE commands in this file automatically provide the
  634. calling convention and naming convention for each Fastgraph routine.  In
  635. addition, they relieve the programmer of distinguishing arguments passed by
  636. value from those passed by reference.
  637.  
  638.                         Example 1-1 (FORTRAN version).
  639.  
  640.      $INCLUDE: '\FG\INTRFACE.FOR'
  641.  
  642.            PROGRAM MAIN
  643.  
  644.            INTEGER*2 MAJOR
  645.            INTEGER*2 MINOR
  646.  
  647.            CALL FG_VERSION (MAJOR, MINOR)
  648.  
  649.            WRITE (6,10) MAJOR, MINOR
  650.      10    FORMAT (' This is version ', I1, '.', I2.2, ' of Fastgraph.')
  651.  
  652.            STOP ' '
  653.            END
  654.  
  655.      You must include the INTERFACE statements in the file INTRFACE.FOR at
  656. the beginning of FORTRAN programs (this file should reside in the \FG
  657. directory).  The INTERFACE statements in this file automatically provide the
  658. calling convention and naming convention for each Fastgraph routine.  In
  659.                                                   Chapter 1:  Introduction   7
  660.  
  661.  
  662. addition, they relieve the FORTRAN programmer of distinguishing arguments
  663. passed by value from those passed by reference.
  664.  
  665.                         Example 1-1 (Pascal version).
  666.  
  667.       program main;
  668.       uses fgmain;
  669.  
  670.       var
  671.         Major : integer;
  672.         Minor : integer;
  673.  
  674.       begin
  675.         fg_version(Major,Minor);
  676.         writeln('This is version ',Major,'.',Minor:2,' of Fastgraph.');
  677.       end.
  678.  
  679.  
  680.      Pascal programs that use Fastgraph or Fastgraph/Light must include a
  681. uses statement specifying the names of the unit files (TPU files) needed in
  682. the program.  All unit files must reside in a directory where the compiler
  683. normally searches for units.  Appendix E lists the Fastgraph functions in
  684. each unit.
  685.  
  686.      The following sections show the simplest compilation and linking
  687. procedures for the supported compilers.  In what follows, items enclosed in
  688. angle brackets, such as <filename>, are placeholders for parameters you must
  689. supply (the name of a file in this case).  Items enclosed in square brackets,
  690. such as [/E], are optional.
  691. 8   Fastgraph User's Guide
  692.  
  693.  
  694.  
  695. Borland C++
  696.  
  697.      Borland C++ allows you to compile and link a program directly from the
  698. DOS command line, or from its integrated development environment (IDE).  To
  699. use Fastgraph from the IDE, you must make sure the compiler options match one
  700. of Fastgraph's available memory models (small, medium, or large) and then
  701. create a project file that links with the corresponding Fastgraph libraries
  702. (as listed below).
  703.  
  704.      You also can compile and link a Borland C++ program from the DOS command
  705. line using the BCC command.  The format of the BCC command for compiling a
  706. program and linking it with Fastgraph is
  707.  
  708.  
  709.              BCC <model> <filename> <fg_library> [<fg_extended>]
  710.  
  711. where:
  712.  
  713.      <model>        specifies the compiler memory model you'll be using.
  714.                     It must be either -ms (for the small model), -mm
  715.                     (for the medium model), or -ml (for the large
  716.                     model).
  717.  
  718.      <filename>     is the name of the file containing your program.  It
  719.                     may include a path specification.
  720.  
  721.      <fg_library>   is the name of a standard Fastgraph or
  722.                     Fastgraph/Light library.  For Fastgraph, the library
  723.                     name is FGS.LIB (for the small model), FGM.LIB (for
  724.                     the medium model), or FGL.LIB (for the large model).
  725.                     For Fastgraph/Light, the library name is FGLS.LIB
  726.                     (for the small model), FGLM.LIB (for the medium
  727.                     model), or FGLL.LIB (for the large model).
  728.  
  729.      <fg_extended>  is the name of an optional compiler-specific
  730.                     extended Fastgraph library.  You need to specify an
  731.                     extended library name only if your program calls any
  732.                     of the Fastgraph routines listed in Appendix D.  The
  733.                     Borland C++ extended library name is FGTCS.LIB (for
  734.                     the small model), FGTCM.LIB (for the medium model),
  735.                     or FGTCL.LIB (for the large model).  Fastgraph/Light
  736.                     does not use extended libraries.
  737.  
  738.      For example, to compile the program 01-01.C under the medium memory
  739. model and then link it with Fastgraph, you could use the following BCC
  740. command:
  741.  
  742.                       BCC -mm 01-01.C FGM.LIB FGTCM.LIB
  743.  
  744. Although we specified the extended library name FGTCM.LIB on the command
  745. line, we didn't need to in this example because the program doesn't call any
  746. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  747. were using Fastgraph/Light instead of Fastgraph, the BCC command would be:
  748.  
  749.                            BCC -mm 01-01.C FGLM.LIB
  750.                                                   Chapter 1:  Introduction   9
  751.  
  752.  
  753. For more information about project files, memory models, or other compilation
  754. and linking options, please refer to the Borland C++ User's Guide, published
  755. by Borland International.
  756. 10   Fastgraph User's Guide
  757.  
  758.  
  759.  
  760. Borland Pascal
  761.  
  762.      Borland Pascal allows you to compile and link a program directly from
  763. the DOS command line with the TPC command, or from its integrated development
  764. environment (IDE) with the TURBO command.  To use Fastgraph from the IDE,
  765. just start the IDE as you would for any other Pascal program, making sure the
  766. Fastgraph unit files reside in one of the directories listed in the Unit
  767. Directories option.
  768.  
  769.      You also can compile and link a Borland Pascal program from the DOS
  770. command line using the TPC command.  The format of the TPC command for
  771. compiling a program and linking it with Fastgraph is
  772.  
  773.                                 TPC <filename>
  774.  
  775. where:
  776.  
  777.      <filename>          is the name of the file containing your
  778.                          program.  It may include a path specification.
  779.  
  780.      For example, to compile the program 01-01.PAS and then link it with
  781. Fastgraph, you could use the following command:
  782.  
  783.                                 TPC 01-01.PAS
  784.  
  785. For more information about other compilation and linking options, please
  786. refer to the Borland Pascal With Objects User's Guide, published by Borland
  787. International.
  788.  
  789.      All remaining example programs in the Fastgraph User's Guide are written
  790. in the C programming language.  However, when you install Fastgraph for
  791. Borland Pascal, the installation procedure copies Pascal versions of the
  792. example programs to the \FG\EXAMPLES directory.
  793.                                                  Chapter 1:  Introduction   11
  794.  
  795.  
  796.  
  797. Microsoft BASIC PDS 7
  798.  
  799.      Microsoft BASIC Professional Development System (PDS) allows you to
  800. compile and link a program directly from the DOS command line, or from its
  801. programming environment.  To use Fastgraph from the BASIC PDS programming
  802. environment, just specify the quick library name FGQBX when starting BASIC
  803. PDS, as shown below.
  804.  
  805.                            QBX /LFGQBX [<filename>]
  806.  
  807. You must use the default "Far Strings" setting within the environment.  There
  808. are no near string Fastgraph libraries available for BASIC PDS.  If you are
  809. using Fastgraph/Light, use the library name FGLQBX instead of FGQBX.
  810.  
  811.      You also can compile and link a BASIC PDS program from the DOS command
  812. line using the BC and LINK commands.  The format of these commands for
  813. compiling a program and linking it with Fastgraph is
  814.  
  815.                   BC /Fs [/O] <filename>;
  816.                   LINK [/E] <object_file>,,NUL,<fg_library>;
  817.  
  818. where:
  819.  
  820.      <filename>     is the name of the file containing your program.  It
  821.                     may include a path specification.
  822.  
  823.      <object_file>  is the name of the object file produced by the BC
  824.                     command.  By default, this will be the same as
  825.                     <filename>, but with an extension of .OBJ rather
  826.                     than .BAS.
  827.  
  828.      <fg_library>   is the name of the standard Fastgraph or
  829.                     Fastgraph/Light library.  For Fastgraph, the library
  830.                     name is FGQBX.  For Fastgraph/Light, the library
  831.                     name is FGLQBX.  QuickBASIC does not use extended
  832.                     Fastgraph libraries.
  833.  
  834. When compiling BASIC PDS programs with the BC command, you must include the
  835. /Fs option to use far strings.  The /O option on the BC command is
  836. recommended because it creates .EXE files that do not require the BASIC PDS
  837. run-time module.  The /E linker option is not required but will produce a
  838. smaller .EXE file if specified.
  839.  
  840.      For example, to compile the program 01-01.BAS and then link it with
  841. Fastgraph, you could use the following commands:
  842.  
  843.                          BC /Fs /O 01-01.BAS;
  844.                          LINK /E 01-01.OBJ,,NUL,FGQBX;
  845.  
  846. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  847. be:
  848.  
  849.                         BC /Fs /O 01-01.BAS;
  850.                         LINK /E 01-01.OBJ,,NUL,FGLQBX;
  851.  
  852. 12   Fastgraph User's Guide
  853.  
  854.  
  855. For more information about other compilation and linking options, please
  856. refer to the Microsoft BASIC PDS Programmer's Guide, published by Microsoft
  857. Corporation.
  858.  
  859.      All remaining example programs in the Fastgraph User's Guide are written
  860. in the C programming language.  However, when you install Fastgraph for
  861. Microsoft BASIC PDS, the installation procedure copies BASIC versions of the
  862. example programs to the \FG\EXAMPLES directory.
  863.                                                  Chapter 1:  Introduction   13
  864.  
  865.  
  866.  
  867. Microsoft C and C++
  868.  
  869.      Microsoft C and C++ programs are compiled and linked by entering a CL
  870. command at the DOS command prompt.  The format of the CL command for
  871. compiling a program and linking it with Fastgraph is
  872.  
  873.         CL <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  874.  
  875. where:
  876.  
  877.      <model>        specifies the compiler memory model you'll be using.
  878.                     It must be either /AS (for the small model), /AM
  879.                     (for the medium model), or /AL (for the large
  880.                     model).
  881.  
  882.      <filename>     is the name of the file containing your program.  It
  883.                     must include the file extension (typically .C) and
  884.                     may include a path specification.
  885.  
  886.      <fg_library>   is the name of a standard Fastgraph or
  887.                     Fastgraph/Light library.  For Fastgraph, the library
  888.                     name is FGS (for the small model), FGM (for the
  889.                     medium model), or FGL (for the large model).  For
  890.                     Fastgraph/Light, the library name is FGLS (for the
  891.                     small model), FGLM (for the medium model), or FGLL
  892.                     (for the large model).
  893.  
  894.      <fg_extended>  is the name of an optional compiler-specific
  895.                     extended Fastgraph library.  You need to specify an
  896.                     extended library name only if your program calls any
  897.                     of the Fastgraph routines listed in Appendix D.  The
  898.                     Microsoft C/C++ extended library name is FGMSCS (for
  899.                     the small model), FGMSCM (for the medium model), or
  900.                     FGMSCL (for the large model).  Fastgraph/Light does
  901.                     not use extended libraries.
  902.  
  903. The /E linker option is not required but will produce a smaller .EXE file if
  904. specified.
  905.  
  906.      For example, to compile the program 01-01.C under the medium memory
  907. model and then link it with Fastgraph, you could use the following CL
  908. command:
  909.  
  910.                       CL /AM 01-01.C /link FGM FGMSCM /E
  911.  
  912. Although we specified the extended library name FGMSCM on the command line,
  913. we didn't need to in this example because the program doesn't call any of the
  914. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  915. Fastgraph/Light instead of Fastgraph, the CL command would be:
  916.  
  917.                          CL /AM 01-01.C /link FGLM /E
  918.  
  919. For more information about memory models or other compilation and linking
  920. options, please refer to the Microsoft C Optimizing Compiler User's Guide,
  921. published by Microsoft Corporation.
  922. 14   Fastgraph User's Guide
  923.  
  924.  
  925.  
  926. Microsoft FORTRAN
  927.  
  928.      Microsoft FORTRAN programs are compiled and linked by entering an FL
  929. command at the DOS command prompt.  The format of the FL command for
  930. compiling a program and linking it with Fastgraph is
  931.  
  932.            FL /FPi /4I2 /4Nt <model> <filename> /link <fg_library>
  933.                [<fg_extended>] [/E]
  934.  
  935. where:
  936.  
  937.      <model>        specifies the compiler memory model you'll be using.
  938.                     It must be either /AM (for the medium model) or /AL
  939.                     (for the large model).  Microsoft FORTRAN does not
  940.                     support the small model.
  941.  
  942.      <filename>     is the name of the file containing your program.  It
  943.                     may include a path specification.
  944.  
  945.      <fg_library>   is the name of a standard Fastgraph or
  946.                     Fastgraph/Light library.  For Fastgraph, the library
  947.                     name is FGM (for the medium model) or FGL (for the
  948.                     large model).  For Fastgraph/Light, the library name
  949.                     is FGLM (for the medium model) or FGLL (for the
  950.                     large model).
  951.  
  952.      <fg_extended>  is the name of an optional compiler-specific
  953.                     extended Fastgraph library.  You need to specify an
  954.                     extended library name only if your program calls any
  955.                     of the Fastgraph routines listed in Appendix D.  The
  956.                     Microsoft FORTRAN extended library name is FGMSFM
  957.                     (for the medium model) or FGMSFL (for the large
  958.                     model).  Fastgraph/Light does not use extended
  959.                     libraries.
  960.  
  961. The /E linker option is not required but will produce a smaller .EXE file if
  962. specified.
  963.  
  964.      For example, to compile the program 01-01.FOR under the medium memory
  965. model and then link it with Fastgraph, you could use the following FL
  966. command:
  967.  
  968.              FL /FPi /4I2 /4Nt /AM 01-01.FOR /link FGM FGMSFM /E
  969.  
  970. Although we specified the extended library name FGMSFM on the command line,
  971. we didn't need to in this example because the program doesn't call any of the
  972. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  973. Fastgraph/Light instead of Fastgraph, the FL command would be:
  974.  
  975.                 FL /FPi /4I2 /4Nt /AM 01-01.FOR /link FGLM /E
  976.  
  977. For more information about memory models or other compilation and linking
  978. options, please refer to the Microsoft FORTRAN Optimizing Compiler User's
  979. Guide, published by Microsoft Corporation.
  980.                                                  Chapter 1:  Introduction   15
  981.  
  982.  
  983.      All remaining example programs in the Fastgraph User's Guide are written
  984. in the C programming language.  However, when you install Fastgraph for the
  985. Microsoft FORTRAN compiler, the installation procedure copies FORTRAN
  986. versions of the example programs to the \FG\EXAMPLES directory.
  987. 16   Fastgraph User's Guide
  988.  
  989.  
  990. Microsoft QuickBASIC
  991.  
  992.      Microsoft QuickBASIC allows you to compile and link a program directly
  993. from the DOS command line, or from its programming environment.  To use
  994. Fastgraph from QuickBASIC's programming environment, just specify the quick
  995. library name FGQB when starting QuickBASIC, as shown below.
  996.  
  997.                             QB /LFGQB [<filename>]
  998.  
  999. If you are using Fastgraph/Light, use the library name FGLQB instead of FGQB.
  1000.  
  1001.      You also can compile and link a QuickBASIC program from the DOS command
  1002. line using the BC and LINK commands.  The format of these commands for
  1003. compiling a program and linking it with Fastgraph is
  1004.  
  1005.                   BC [/O] <filename>;
  1006.                   LINK [/E] <object_file>,,NUL,<fg_library>;
  1007.  
  1008. where:
  1009.  
  1010.      <filename>     is the name of the file containing your program.  It
  1011.                     may include a path specification.
  1012.  
  1013.      <object_file>  is the name of the object file produced by the BC
  1014.                     command.  By default, this will be the same as
  1015.                     <filename>, but with an extension of .OBJ rather
  1016.                     than .BAS.
  1017.  
  1018.      <fg_library>   is the name of the standard Fastgraph or
  1019.                     Fastgraph/Light library.  For Fastgraph, the library
  1020.                     name is FGQB.  For Fastgraph/Light, the library name
  1021.                     is FGLQB.  QuickBASIC does not use extended
  1022.                     Fastgraph libraries.
  1023.  
  1024. The /O option on the BC command is recommended because it creates .EXE files
  1025. that do not require the QuickBASIC run-time module.  The /E linker option is
  1026. not required but will produce a smaller .EXE file if specified.
  1027.  
  1028.      For example, to compile the program 01-01.BAS and then link it with
  1029. Fastgraph, you could use the following commands:
  1030.  
  1031.                          BC /O 01-01.BAS;
  1032.                          LINK /E 01-01.OBJ,,NUL,FGQB;
  1033.  
  1034. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  1035. be:
  1036.  
  1037.                          BC /O 01-01.BAS;
  1038.                          LINK /E 01-01.OBJ,,NUL,FGLQB;
  1039.  
  1040. For more information about other compilation and linking options, please
  1041. refer to the Microsoft QuickBASIC: Programming in BASIC manual, published by
  1042. Microsoft Corporation.
  1043.  
  1044.      All remaining example programs in the Fastgraph User's Guide are written
  1045. in the C programming language.  However, when you install Fastgraph for
  1046.                                                  Chapter 1:  Introduction   17
  1047.  
  1048.  
  1049. Microsoft QuickBASIC, the installation procedure copies BASIC versions of the
  1050. example programs to the \FG\EXAMPLES directory.
  1051. 18   Fastgraph User's Guide
  1052.  
  1053.  
  1054. Microsoft QuickC
  1055.  
  1056.      Microsoft QuickC allows you to compile and link a program directly from
  1057. the DOS command line, or from its programming environment.  To use Fastgraph
  1058. from the QuickC programming environment, you must make sure the compiler
  1059. options match one of Fastgraph's available memory models (small, medium, or
  1060. large) and then create a make file that includes one or more of the
  1061. corresponding Fastgraph libraries (as listed below).
  1062.  
  1063.      You also can compile and link a QuickC program from the DOS command line
  1064. using the QCL command.  The format of the QCL command for compiling a program
  1065. and linking it with Fastgraph is
  1066.  
  1067.         QCL <model> <filename> /link <fg_library> [<fg_extended>] [/E]
  1068.  
  1069. where:
  1070.  
  1071.      <model>        specifies the compiler memory model you'll be using.
  1072.                     It must be either /AS (for the small model), /AM
  1073.                     (for the medium model), or /AL (for the large
  1074.                     model).
  1075.  
  1076.      <filename>     is the name of the file containing your program.  It
  1077.                     must include the file extension (typically .C) and
  1078.                     may include a path specification.
  1079.  
  1080.      <fg_library>   is the name of a standard Fastgraph or
  1081.                     Fastgraph/Light library.  For Fastgraph, the library
  1082.                     name is FGS (for the small model), FGM (for the
  1083.                     medium model), or FGL (for the large model).  For
  1084.                     Fastgraph/Light, the library name is FGLS (for the
  1085.                     small model), FGLM (for the medium model), or FGLL
  1086.                     (for the large model).
  1087.  
  1088.      <fg_extended>  is the name of an optional compiler-specific
  1089.                     extended Fastgraph library.  You need to specify an
  1090.                     extended library name only if your program calls any
  1091.                     of the Fastgraph routines listed in Appendix D.  The
  1092.                     QuickC extended library name is FGMSCS (for the
  1093.                     small model), FGMSCM (for the medium model), or
  1094.                     FGMSCL (for the large model).  Fastgraph/Light does
  1095.                     not use extended libraries.
  1096.  
  1097. The /E linker option is not required but will produce a smaller .EXE file if
  1098. specified.
  1099.  
  1100.      For example, to compile the program 01-01.C under the medium memory
  1101. model and then link it with Fastgraph, you could use the following QCL
  1102. command:
  1103.  
  1104.                      QCL /AM 01-01.C /link FGM FGMSCM /E
  1105.  
  1106. Although we specified the extended library name FGMSCM on the command line,
  1107. we didn't need to in this example because the program doesn't call any of the
  1108. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  1109. Fastgraph/Light instead of Fastgraph, the QCL command would be:
  1110.                                                  Chapter 1:  Introduction   19
  1111.  
  1112.  
  1113.  
  1114.                         QCL /AM 01-01.C /link FGLM /E
  1115.  
  1116. For more information about make files, memory models, or other compilation
  1117. and linking options, please refer to the Microsoft QuickC Tool Kit manual,
  1118. published by Microsoft Corporation.
  1119. 20   Fastgraph User's Guide
  1120.  
  1121.  
  1122.  
  1123. Microsoft Visual Basic for DOS
  1124.  
  1125.      Microsoft Visual Basic for DOS allows you to compile and link a program
  1126. directly from the DOS command line, or from its programming environment.  To
  1127. use Fastgraph from the programming environment, just specify the quick
  1128. library name FGVBDOS when starting Visual Basic, as shown below.
  1129.  
  1130.                          VBDOS /LFGVBDOS [<filename>]
  1131.  
  1132. If you are using Fastgraph/Light, use the library name FGLVBDOS instead of
  1133. FGVBDOS.  When using the Visual Basic for DOS programming environment, you
  1134. may get an "Out of Memory" or "Out of String Space" error message when trying
  1135. to build an EXE file or run an application within the environment.  Should
  1136. this occur, you must specify the /S option on the VBDOS command line to
  1137. increase the amount of memory available to your application.
  1138.  
  1139.      You also can compile and link a Visual Basic program from the DOS
  1140. command line using the BC and LINK commands.  The format of these commands
  1141. for compiling a program and linking it with Fastgraph is
  1142.  
  1143.                   BC [/O] <filename>;
  1144.                   LINK [/E] <object_file>,,NUL,<fg_library>;
  1145.  
  1146. where:
  1147.  
  1148.      <filename>     is the name of the file containing your program.  It
  1149.                     may include a path specification.
  1150.  
  1151.      <object_file>  is the name of the object file produced by the BC
  1152.                     command.  By default, this will be the same as
  1153.                     <filename>, but with an extension of .OBJ rather
  1154.                     than .BAS.
  1155.  
  1156.      <fg_library>   is the name of the standard Fastgraph or
  1157.                     Fastgraph/Light library.  For Fastgraph, the library
  1158.                     name is FGVBDOS.  For Fastgraph/Light, the library
  1159.                     name is FGLVBDOS.  Visual Basic does not use
  1160.                     extended Fastgraph libraries.
  1161.  
  1162. The /O option on the BC command is recommended because it creates .EXE files
  1163. that do not require the Visual Basic run-time module.  The /E linker option
  1164. is not required but will produce a smaller .EXE file if specified.
  1165.  
  1166.      For example, to compile the program 01-01.BAS and then link it with
  1167. Fastgraph, you could use the following commands:
  1168.  
  1169.                          BC /O 01-01.BAS;
  1170.                          LINK /E 01-01.OBJ,,NUL,FGVBDOS;
  1171.  
  1172. If you were using Fastgraph/Light instead of Fastgraph, the commands would
  1173. be:
  1174.  
  1175.                          BC /O 01-01.BAS;
  1176.                          LINK /E 01-01.OBJ,,NUL,FGLVBDOS;
  1177.  
  1178.                                                  Chapter 1:  Introduction   21
  1179.  
  1180.  
  1181. When linking Visual Basic for DOS programs that call Fastgraph's world space
  1182. or software character routines (i.e., any of the routines listed in Appendix
  1183. D), you may need to increase the number of segments available to the linker.
  1184. Use the /SEG:n option on the LINK command to do this.  The default value of
  1185. "n" is 128 segments; usually a slightly larger value, such as 144, will be
  1186. sufficient.  For more information about other compilation and linking
  1187. options, please refer to the Microsoft Visual Basic Programmer's Guide,
  1188. published by Microsoft Corporation.
  1189.  
  1190.      All remaining example programs in the Fastgraph User's Guide are written
  1191. in the C programming language.  However, when you install Fastgraph for
  1192. Visual Basic, the installation procedure copies BASIC versions of the example
  1193. programs to the \FG\EXAMPLES directory.
  1194. 22   Fastgraph User's Guide
  1195.  
  1196.  
  1197.  
  1198. Microsoft Visual C++
  1199.  
  1200.      To use Fastgraph with Microsoft Visual C++, use the same compilation
  1201. sequences as for Microsoft C and C++.
  1202.                                                  Chapter 1:  Introduction   23
  1203.  
  1204.  
  1205.  
  1206. Power C
  1207.  
  1208.      Power C programs are compiled and linked from the DOS command line using
  1209. the PC and PCL commands.  The format of these commands for compiling a
  1210. program and linking it with Fastgraph is
  1211.  
  1212.                 PC <model> <filename>
  1213.                 PCL <mix_file> ;<fg_library> [;<fg_extended>]
  1214.  
  1215. where:
  1216.  
  1217.      <model>        specifies the compiler memory model you'll be using.
  1218.                     It must be either /ms (for the small model), /mm
  1219.                     (for the medium model), or /ml (for the large
  1220.                     model).
  1221.  
  1222.      <filename>     is the name of the file containing your program.  It
  1223.                     may include a path specification.
  1224.  
  1225.      <mix_file>     is the name of the object file produced by the PC
  1226.                     command.  By default, this will be the same as
  1227.                     <filename>, but with an extension of .MIX rather
  1228.                     than .C.
  1229.  
  1230.      <fg_library>   is the name of a standard Fastgraph or
  1231.                     Fastgraph/Light library.  For Fastgraph, the library
  1232.                     name is FGS (for the small model), FGM (for the
  1233.                     medium model), or FGL (for the large model).  For
  1234.                     Fastgraph/Light, the library name is FGLS (for the
  1235.                     small model), FGLM (for the medium model), or FGLL
  1236.                     (for the large model).
  1237.  
  1238.      <fg_extended>  is the name of an optional compiler-specific
  1239.                     extended Fastgraph library.  You need to specify an
  1240.                     extended library name only if your program calls any
  1241.                     of the Fastgraph routines listed in Appendix D.  The
  1242.                     Power C extended library name is FGPCS (for the
  1243.                     small model), FGPCM (for the medium model), or FGPCL
  1244.                     (for the large model).  Fastgraph/Light does not use
  1245.                     extended libraries.
  1246.  
  1247.      For example, to compile the program 01-01.C under the medium memory
  1248. model and then link it with Fastgraph, you could use the following commands:
  1249.  
  1250.                           PC /mm 01-01.C
  1251.                           PCL 01-01.MIX ;FGM ;FGPCM
  1252.  
  1253. Although we specified the extended library name FGPCM on the command line, we
  1254. didn't need to in this example because the program doesn't call any of the
  1255. compiler-specific Fastgraph routines listed in Appendix D.  If you were using
  1256. Fastgraph/Light instead of Fastgraph, the commands would be:
  1257.  
  1258.                              PC /mm 01-01.C
  1259.                              PCL 01-01.MIX ;FGPCM
  1260.  
  1261. 24   Fastgraph User's Guide
  1262.  
  1263.  
  1264. For more information about memory models or other compilation and linking
  1265. options, please refer to the Power C manual, published by Mix Software, Inc.
  1266.                                                  Chapter 1:  Introduction   25
  1267.  
  1268.  
  1269.  
  1270. Turbo C and Turbo C++
  1271.  
  1272.      Turbo C and Turbo C++ allow you to compile and link a program directly
  1273. from the DOS command line, or from their integrated development environment
  1274. (IDE).  To use Fastgraph from the IDE, you must make sure the compiler
  1275. options match one of Fastgraph's available memory models (small, medium, or
  1276. large) and then create a project file that links with the corresponding
  1277. Fastgraph libraries (as listed below).
  1278.  
  1279.      You also can compile and link a Turbo C or Turbo C++ program from the
  1280. DOS command line using the TCC command.  The format of the TCC command for
  1281. compiling a program and linking it with Fastgraph is
  1282.  
  1283.              TCC <model> <filename> <fg_library> [<fg_extended>]
  1284.  
  1285. where:
  1286.  
  1287.      <model>        specifies the compiler memory model you'll be using.
  1288.                     It must be either -ms (for the small model), -mm
  1289.                     (for the medium model), or -ml (for the large
  1290.                     model).
  1291.  
  1292.      <filename>     is the name of the file containing your program.  It
  1293.                     may include a path specification.
  1294.  
  1295.      <fg_library>   is the name of a standard Fastgraph or
  1296.                     Fastgraph/Light library.  For Fastgraph, the library
  1297.                     name is FGS.LIB (for the small model), FGM.LIB (for
  1298.                     the medium model), or FGL.LIB (for the large model).
  1299.                     For Fastgraph/Light, the library name is FGLS.LIB
  1300.                     (for the small model), FGLM.LIB (for the medium
  1301.                     model), or FGLL.LIB (for the large model).
  1302.  
  1303.      <fg_extended>  is the name of an optional compiler-specific
  1304.                     extended Fastgraph library.  You need to specify an
  1305.                     extended library name only if your program calls any
  1306.                     of the Fastgraph routines listed in Appendix D.  The
  1307.                     Turbo C/C++ extended library name is FGTCS.LIB (for
  1308.                     the small model), FGTCM.LIB (for the medium model),
  1309.                     or FGTCL.LIB (for the large model).  Fastgraph/Light
  1310.                     does not use extended libraries.
  1311.  
  1312.      For example, to compile the program 01-01.C under the medium memory
  1313. model and then link it with Fastgraph, you could use the following TCC
  1314. command:
  1315.  
  1316.                       TCC -mm 01-01.C FGM.LIB FGTCM.LIB
  1317.  
  1318. Although we specified the extended library name FGTCM.LIB on the command
  1319. line, we didn't need to in this example because the program doesn't call any
  1320. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  1321. were using Fastgraph/Light instead of Fastgraph, the TCC command would be:
  1322.  
  1323.                            TCC -mm 01-01.C FGLM.LIB
  1324.  
  1325. 26   Fastgraph User's Guide
  1326.  
  1327.  
  1328. For more information about project files, memory models, or other compilation
  1329. and linking options, please refer to the Turbo C User's Guide and the Turbo C
  1330. Reference Guide, both published by Borland International.
  1331.                                                  Chapter 1:  Introduction   27
  1332.  
  1333.  
  1334.  
  1335. Turbo Pascal
  1336.  
  1337.      Turbo Pascal allows you to compile and link a program directly from the
  1338. DOS command line with the TPC command, or from its integrated development
  1339. environment (IDE) with the TURBO command.  To use Fastgraph from the IDE,
  1340. just start the IDE as you would for any other Pascal program, making sure the
  1341. Fastgraph unit files reside in one of the directories listed in the Unit
  1342. Directories option.
  1343.  
  1344.      You also can compile and link a Turbo Pascal program from the DOS
  1345. command line using the TPC command.  The format of the TPC command for
  1346. compiling a program and linking it with Fastgraph is
  1347.  
  1348.                                 TPC <filename>
  1349.  
  1350. where:
  1351.  
  1352.      <filename>          is the name of the file containing your
  1353.                          program.  It may include a path specification.
  1354.  
  1355.      For example, to compile the program 01-01.PAS and then link it with
  1356. Fastgraph, you could use the following command:
  1357.  
  1358.                                 TPC 01-01.PAS
  1359.  
  1360. For more information about other compilation and linking options, please
  1361. refer to the Turbo Pascal User's Guide, published by Borland International.
  1362.  
  1363.      All remaining example programs in the Fastgraph User's Guide are written
  1364. in the C programming language.  However, when you install Fastgraph for Turbo
  1365. Pascal, the installation procedure copies Pascal versions of the example
  1366. programs to the \FG\EXAMPLES directory.
  1367. 28   Fastgraph User's Guide
  1368.  
  1369.  
  1370.  
  1371. Zortech C++
  1372.  
  1373.      Zortech C++ programs are compiled and linked from the DOS command line
  1374. using the ZTC command.  The format of this command for compiling a program
  1375. and linking it with Fastgraph is
  1376.  
  1377.              ZTC <model> <filename> <fg_library> [<fg_extended>]
  1378.  
  1379. where:
  1380.  
  1381.      <model>        specifies the compiler memory model you'll be using.
  1382.                     It must be either -ms (for the small model), -mm
  1383.                     (for the medium model), or -ml (for the large
  1384.                     model).
  1385.  
  1386.      <filename>     is the name of the file containing your program.  It
  1387.                     may include a path specification.
  1388.  
  1389.      <fg_library>   is the name of a standard Fastgraph or
  1390.                     Fastgraph/Light library.  For Fastgraph, the library
  1391.                     name is FGS.LIB (for the small model), FGM.LIB (for
  1392.                     the medium model), or FGL.LIB (for the large model).
  1393.                     For Fastgraph/Light, the library name is FGLS.LIB
  1394.                     (for the small model), FGLM.LIB (for the medium
  1395.                     model), or FGLL.LIB (for the large model).
  1396.  
  1397.      <fg_extended>  is the name of an optional compiler-specific
  1398.                     extended Fastgraph library.  You need to specify an
  1399.                     extended library name only if your program calls any
  1400.                     of the Fastgraph routines listed in Appendix D.  The
  1401.                     Zortech C++ extended library name is FGZCS.LIB (for
  1402.                     the small model), FGZCM.LIB (for the medium model),
  1403.                     or FGZCL.LIB (for the large model).  Fastgraph/Light
  1404.                     does not use extended libraries.
  1405.  
  1406.      For example, to compile the program 01-01.C under the medium memory
  1407. model and then link it with Fastgraph, you could use the following ZTC
  1408. command:
  1409.  
  1410.                       ZTC -mm 01-01.C FGM.LIB FGZCM.LIB
  1411.  
  1412. Although we specified the extended library name FGZCM.LIB on the command
  1413. line, we didn't need to in this example because the program doesn't call any
  1414. of the compiler-specific Fastgraph routines listed in Appendix D.  If you
  1415. were using Fastgraph/Light instead of Fastgraph, the TCC command would be:
  1416.  
  1417.                            ZTC -mm 01-01.C FGLM.LIB
  1418.  
  1419. For more information about memory models or other compilation and linking
  1420. options, please refer to the manuals supplied with your Zortech C++ compiler.
  1421.                                                  Chapter 1:  Introduction   29
  1422.  
  1423.  
  1424.  
  1425. Fastgraph/Light Video Driver
  1426.  
  1427.      As mentioned earlier, running any program created with Fastgraph/Light
  1428. requires an external program called the Fastgraph/Light Video Driver.  The
  1429. video driver is a terminate and stay resident program (TSR) that provides an
  1430. interface between your program and Fastgraph.  Once loaded, the video driver
  1431. uses over 100,000 bytes of conventional memory.
  1432.  
  1433.      To load the video driver, enter the command FGDRIVER at the DOS command
  1434. prompt (assuming FGDRIVER.EXE is in the current directory, or the \FG
  1435. directory is in your DOS path specification).  The driver will display a
  1436. message indicating whether or not it loaded successfully.  After you load the
  1437. driver, just run a program created with Fastgraph/Light as you would any
  1438. other program.  If you try running a program that uses Fastgraph/Light
  1439. without first loading the video driver, the message "Fastgraph/Light video
  1440. driver not installed" will appear.
  1441.  
  1442.      You don't need to load the driver before running each program, just once
  1443. per system boot (in fact, the driver will display an "already loaded" message
  1444. if you try to load it more than once).  If you want to unload the video
  1445. driver, just enter FGDRIVER /U at the DOS command prompt.  The unload
  1446. operation will work completely only if the video driver was the last TSR
  1447. loaded.  If it wasn't the last TSR, the driver will still unload, but the
  1448. memory it uses will not be released back to DOS.
  1449. 30   Fastgraph User's Guide
  1450.